home *** CD-ROM | disk | FTP | other *** search
/ STraTOS 1997 April & May / STraTOS 1 - 1997 April & May.iso / CD01 / DISK / XHDI-125.ZOO / xhdispec.txt < prev   
Encoding:
Text File  |  1994-10-09  |  25.2 KB  |  609 lines
  1. @(#)XHDI/xhdispec.txt
  2. @(#)Julian F. Reschke, 9. Oktober 1994
  3.  
  4. Spezifikation des `XHDI'-Cookies, 9. Oktober 1994
  5. -------------------------------------------------
  6.  
  7. Cookie-Kennung: "XHDI". Der Parameter zeigt auf die Adresse einer 
  8. Routine, die massenspeicherbezogene Funktionen zur Verfügung stellt. Zur 
  9. Absicherung steht vor der Routine die Long-Konstante $27011992.
  10.  
  11. Der Wert des Cookies kann sich im laufenden Betrieb ändern (wg. 
  12. Zweitinstallation). Daher ggfs. (z. B. in Accessories) den Cookie 
  13. jedesmal NEU abfragen!
  14.  
  15. ALLE FUNKTIONEN MUESSEN IM SUPERVISOR-MODUS AUFGERUFEN WERDEN. Das 
  16. Verhalten für Aufrufe im User-Modus ist undefiniert. Bis auf D0 werden 
  17. keine Prozessorregister verändert. Undefinierte Opcodes führen zur 
  18. Fehlermeldung EINVFN.
  19.  
  20. Einige der Funktionsaufrufe -- insbesondere `XHReadWrite()' -- können 
  21. zum Aufruf von BIOS- oder XBIOS-Routinen im Betriebssystem und damit zur 
  22. Aktivierung des `Critical Error Handler' führen. Im Zweifel mu₧ der 
  23. `CEH' also vom Aufrufer abgeschaltet werden.
  24.  
  25. Für alle Funktionen seien folgende Return-Werte definiert:
  26.  
  27. TOS-Fehlernummern:
  28.  
  29. 0:           OK (OK)
  30. -1:          unspezifizierter Fehler (ERROR)
  31. -2:          Gerät nicht bereit (EDRVNR)
  32. -15:         ungültige Device/Targetnummer (EUNDEV)
  33. -32:         falsche Funktionsnummer (EINVFN)
  34. -36:         Gerät ist zur Zeit 'reserved' (EACCDN)
  35. -46:         BIOS-Device wird vom Treiber nicht bedient (EDRIVE)
  36.  
  37. SCSI-Fehlernummern (Bereich von -200..-455)
  38.  
  39. (-200 - N):  SCSI-Errorcode N (der `Additional Sense Code' aus Byte 12 des
  40.              `Extended Sense Format', siehe Abschnitt 7.2.14 in `draft
  41.              proposed American National Standard for information systems -
  42.              SMALL COMPUTER SYSTEM INTERFACE - 2 (SCSI-2) March 9, 1990').
  43.  
  44. IDE-Fehlernummern (Bereich von -456..-711)
  45.  
  46. (-456 - N):  IDE-Errorcode N (Wert des IDE-Fehlerregisters).             
  47.  
  48. Hinweis: SCSI-Fehlercodes können logischerweise nur bei ACSI-/SCSI-
  49. Geräten auftreten. Für Platten am IDE-Interface des `ST-Book' oder 
  50. `Falcon030' (oder Maschinen, bei denen ein derartiges Interface 
  51. nachgerüstet worden ist), kann auch optional folgende Zuordnung benutzt 
  52. werden:
  53.  
  54. Bit im IDE-
  55. Fehlerregister  Bedeutung                  SCSI-Fehler  XHDI-Fehler
  56.  
  57. 1               Track 0 not found          $06          -206
  58. 0               DAM not found              $13          -219
  59. 4               ID-Field not found         $12          -218
  60. 7               Bad block mark             $10          -216
  61. 6               Uncorrectable error        $11          -217
  62. 2               Command aborted            $20          -232
  63. 5               Media Change               $28          -240
  64. 3               Media Change requested     $5A          -290
  65.  
  66. (es empfiehlt sich, die einzelnen Bits in der angegebenen Reihenfolge
  67. zu testen).
  68.  
  69. Bei andersartigen Geräten, wie zum Beispiel Diskettenlaufwerken an der 
  70. Floppy-Controller-Schnittstelle, können auch andere, hier noch nicht 
  71. spezifizierte Error-Codes zurückgeliefert werden.
  72.  
  73. Für die Parameterübergabe gilt die GEMDOS-Übergabe-Konvention. Alle 
  74. Parameter werden auf dem Stack abgelegt (zuletzt, also an der niedrigsten 
  75. Adresse, der Opcode als 16-Bit-Wert). Das 32 Bit gro₧e Ergebnis wird in D0 
  76. zurückgeliefert.
  77.  
  78. Immer dann, wenn dokumentiert ist, da₧ der Aufrufer Nullzeiger übergeben 
  79. darf, bedeutet die Übergabe eines Nullzeigers, da₧ der Aufrufer sich für 
  80. den zurückzuliefernden Wert nicht interessiert. Treibersoftware mu₧ also 
  81. solche Zeiger vor einer Dereferenzierung immer überprüfen.
  82.  
  83. Folgende Datentypen seien vereinbart:
  84.  
  85. UWORD:  16-Bit, unsigned
  86. LONG:   32-Bit, signed
  87. ULONG:  32-Bit, unsigned
  88. char *: 32-Bit, Zeiger auf eine nullterminierte Zeichenkette
  89.  
  90. Termini:
  91.  
  92. major:  Major Device Number
  93.  
  94.            0..7: Platten am ACSI-Bus mit Atari-kompatiblen Befehlssatz
  95.           8..15: Platten am SCSI-Bus
  96.          16..17: Platten an der IDE-Schnittstelle
  97.          18..63: Erweiterungen lt. PUN_INFO-Struktur (Feld: pun[])
  98.              64: Gerät am Floppycontroller
  99.         65..255: weitere eigene Erweiterungen jenseits dem, was AHDI
  100.                  abdeckt
  101.  
  102. minor:  Minor Device Number (für 'major' 0..15: LUN des ACSI- oder
  103.         SCSI-Geräts), maximal 255.
  104.  
  105. key:    Entweder ein 16-Bit-Schlüssel, ermittelt von `XHReserve()', oder 0,
  106.         wenn das Gerät nicht reserviert wurde oder der Schlüssel nicht
  107.         bekannt ist.
  108.  
  109.  
  110. Die einzelnen Funktionen:
  111.  
  112. -----------------------------------------------------------------------
  113. Opcode 0: UWORD XHGetVersion (void);
  114.  
  115. Liefert die Protokollversion zurück. Formatbeispiel: $0119 ist Version 
  116. 1.19 (identisch mit GEMDOS-Sversion(), nur sind die beiden Bytes NICHT 
  117. verdreht). Diese Version der XHDI-Spezifikation hat die Versionsnummer 
  118. $0125.
  119.  
  120. -----------------------------------------------------------------------
  121. Opcode 1: LONG XHInqTarget (UWORD major, UWORD minor, ULONG *blocksize,
  122.                             ULONG *device_flags, char *product_name);
  123.  
  124. Liefert Informationen über das durch `major' und `minor' spezifizierte 
  125. Gerät (in `device_flags': ein Attributvektor, in `product_name': 
  126. optional die Produktbezeichnung des Geräts). Mit `XHReserve ()' 
  127. vorgenommene Reservierungen werden dabei berücksichtigt.
  128.  
  129. block_size:   Blockgrö₧e auf dem Gerät (für `XHReadWrite()' sehr wichtig).
  130.               Normalerweise 512.
  131.  
  132. device_flags: (Bit gesetzt -> Fähigkeit verfügbar):
  133.  
  134.       Bit 0:  Gerät kann gestoppt werden (XH_TARGET_STOPPABLE)
  135.       Bit 1:  Gerät hat wechselbare Medien (XH_TARGET_REMOVABLE)
  136.       Bit 2:  Auswurf des Geräts kann verriegelt werden
  137.               (XH_TARGET_LOCKABLE)
  138.       Bit 3:  Medium kann per Kommando ausgeworfen werden
  139.               (XH_TARGET_EJECTABLE)
  140.       Bit 29: Auswurf des Geräts ist vom Treiber blockiert worden 
  141.               (XH_TARGET_LOCKED, ab XHDI 1.25).
  142.       Bit 30: Gerät ist vom Treiber gestoppt worden (XH_TARGET_STOPPED, 
  143.               ab XHDI 1.25).
  144.       Bit 31: Gerät ist zur Zeit blockiert (XH_TARGET_RESERVED).
  145.  
  146.               Alle weiteren Bits sind reserviert und sollten vom Treiber
  147.               auf Null gesetzt werden.
  148.  
  149. product_name: Produktbezeichnung des Geräts (max. 33 Zeichen inkl.
  150.               Leerzeichen). Falls die Information nicht verfügbar ist, wird
  151.               eine Zeichenkette der Länge Null zurückgeliefert.
  152.  
  153. Anmerkung: für `blocksize', `device_flags' und `product_name' dürfen 
  154. auch Nullzeiger übergeben werden.
  155.  
  156. Anmerkung: für IDE-Geräte wird bei `product_name' gegebenenfalls auf 32 
  157. Zeichen gekürzt. Siehe auch die neue Funktion `XHInqTarget2'.
  158.  
  159. -----------------------------------------------------------------------
  160. Opcode 2: LONG XHReserve (UWORD major, UWORD minor, UWORD do_reserve,
  161.                           UWORD key);
  162.  
  163. Reserviert ein Gerät bzw. gibt es wieder frei. Auf reservierte Geräte 
  164. kann nur bei Angabe des korrekten Schlüssels per `XHLock()', `XHStop()' 
  165. oder `XHEject()' zugegriffen werden.
  166.  
  167. Sinn: man möchte nicht, da₧ man eine Wechselplatte per CPX-Modul 
  168. entriegeln kann, nachdem sie gerade von einer virtuellen 
  169. Speicherverwaltung verriegelt worden ist. Dies sollte nur die 
  170. Speicherverwaltung selbst machen können.
  171.  
  172. Beim Reservieren des Geräts wird im Erfolgsfall ein 16-Bit-Schlüssel 
  173. zurückgeliefert. Dieser Schlüssel mu₧ bei allen weiteren Zugriffen auf 
  174. das Gerät angegeben sowie beim Wieder-Freigeben angegeben werden.
  175.  
  176. do_reserve: (1) Reservieren oder (0) wieder freigeben.
  177. key:        (nur beim Freigeben benutzt).
  178.  
  179. -----------------------------------------------------------------------
  180. Opcode 3: LONG XHLock (UWORD major, UWORD minor, UWORD do_lock,
  181.                        UWORD key);
  182.  
  183. Verriegelt bzw. entriegelt den Auswurfknopf eines Geräts. Der Treiber 
  184. hat sich darum zu kümmern, ob dieser Befehl an das Gerät weitergeleitet 
  185. wird oder nicht (falls das Medium nicht verriegelbar ist).
  186.  
  187. Welchen Code man im Fehlerfall zurückerhält, ist undefiniert. Mehr 
  188. Informationen werden allerdings auch nicht benötigt, da man ja mit 
  189. `XHInqTarget()' vorher gezielt auf diese Fähigkeit abtesten kann.
  190.  
  191. do_lock: (1) Verriegeln oder (0) Entriegeln.
  192. key:     Falls Gerät reserviert, sonst Null übergeben.
  193.  
  194. -----------------------------------------------------------------------
  195. Opcode 4: LONG XHStop (UWORD major, UWORD minor, UWORD do_stop,
  196.                        UWORD key);
  197.  
  198. Gerät wird gestoppt (geparkt) bzw. gestartet (entparkt).
  199.  
  200. Welchen Code man im Fehlerfall zurückerhält, ist undefiniert. Mehr 
  201. Informationen werden allerdings auch nicht benötigt, da man ja mit 
  202. `XHInqTarget()' vorher gezielt auf diese Fähigkeit abtesten kann.
  203.  
  204. do_stop: (1) Stoppen oder (0) Starten.
  205. key:     Falls Gerät reserviert, sonst Null übergeben.
  206.  
  207. Anmerkung: Bei etwaigen Zugriffen auf das gestoppte Gerät sollte der 
  208. Treiber selbst für das Wiederhochfahren sorgen.
  209.  
  210.  
  211. -----------------------------------------------------------------------
  212. Opcode 5: LONG XHEject (UWORD major, UWORD minor, UWORD do_eject,
  213.                         UWORD key);
  214.  
  215. Medium wird ausgeworfen oder eingezogen.
  216.  
  217. Welchen Code man im Fehlerfall zurückerhält, ist undefiniert. Mehr 
  218. Informationen werden allerdings auch nicht benötigt, da man ja mit 
  219. `XHInqTarget()' vorher gezielt auf diese Fähigkeit abtesten kann.
  220.  
  221. do_eject: Medium auswerfen (1) oder einziehen (0).
  222. key:      Falls Gerät reserviert, sonst Null übergeben.
  223.  
  224. -----------------------------------------------------------------------
  225. Opcode 6: ULONG XHDrvMap (void);
  226.  
  227. Liefert einen Bitvektor mit den über das XHDI-Protokoll unterstützten 
  228. BIOS-Gerätenummern (wie etwa bei `Drvmap()').
  229.  
  230. -----------------------------------------------------------------------
  231. Opcode 7: LONG XHInqDev (UWORD bios_device, UWORD *major, UWORD *minor,
  232.                          ULONG *start_sector, BPB *bpb);
  233.  
  234. Liefert Major Device Number, Minor Device Number, Startsektor und BPB 
  235. eines BIOS-Geräts (im Gegensatz zu `Getbpb()' wird dadurch der Media-
  236. Change-Status des Geräts NICHT zurückgesetzt).
  237.  
  238. Anmerkung: es wird ein Zeiger auf eine vom Aufrufer bereitgestellte BPB-
  239. Struktur übergeben, die vom XHDI-Treiber gefüllt wird.
  240.  
  241. Return-Wert: OK, EDRVNR (Gerät kann zur Zeit nicht angesprochen werden, 
  242. zum Beispiel Medium nicht eingelegt), EDRIVE (falsche Gerätenummer) oder 
  243. eine andere Fehlernummer. Bei EDRVNR darf man sich darauf verlassen, da₧ 
  244. `major' und `minor' korrekt zurückgeliefert werden.
  245.  
  246. Ein `start_sector' mit Wert $FFFFFFFF soll auf eine Partition hinweisen, 
  247. die zur Zeit vom Treiber nicht bedient wird (zum Beispiel, wenn ein 
  248. Wechselmedium mit 'zu wenig' Partitionen eingelegt ist).
  249.  
  250. Der zurückgelieferte BPB ist ungültig, wenn das Element `recsiz' Null ist.
  251.  
  252. Hinweis: ein Dateisystem ist durch major- und minor-Gerätenummer sowie 
  253. Startsektor (mit der obigen Einschränkung) exakt spezifiziert. Über die 
  254. Art des Dateisystems (FAT oder etwas anderes) ist damit nichts ausgesagt!
  255.  
  256. Anmerkung: für `major', `minor', `start_sector' und `bpb' dürfen auch 
  257. Nullzeiger übergeben werden.
  258.  
  259. -----------------------------------------------------------------------
  260. Opcode 8: LONG XHInqDriver (UWORD bios_device, char *name, char *version,
  261.                             char *company, UWORD *ahdi_version,
  262.                             UWORD *maxIPL);
  263.  
  264. Liefert Informationen über den Treiber, der das angegebene Gerät bedient.
  265.  
  266. name:         Zeiger auf Zeichenkette mit Treibernamen (max. 17 Zeichen).
  267. version:      Zeiger auf Zeichenkette mit Versionsnummer (max. 7 Zeichen).
  268. company:      Zeiger auf Zeichenkette mit Namen des Herstellers (max. 17
  269.               Zeichen).
  270. ahdi_version: AHDI-Versionslevel (wie PUN_INFO-Struktur).
  271. maxIPL:       Höchster IPL, unter dem der Treiber für das angegebene Gerät
  272.               arbeitsfähig ist (Normalwert für Treiber, die ihr Timing per
  273.               _hz_200 erledigen: 5).
  274.  
  275. Anmerkung: für `name', `version', `company', `ahdi_version' und 
  276. `maxIPL' dürfen auch Nullzeiger übergeben werden.
  277.  
  278. -----------------------------------------------------------------------
  279. Opcode 9: LONG XHNewCookie (ULONG newcookie);
  280.  
  281. - OPTIONALE Funktion, darf also mit EINVFN beantwortet werden -
  282.  
  283. Installiert einen zusätzlichen XHDI-Handler (Vorteil: der XHDI-Cookie 
  284. zeigt nach wie vor auf die gleiche Adresse). Wer diese Funktion 
  285. unterstützt mu₧ also folgendes tun:
  286.  
  287. 1. Falls dies der erste Aufruf dieser Art ist: anschlie₧end so vorgehen,
  288.    als hätte der XHDI-Cookie bei der Installation bereits auf `newcookie'
  289.    gezeigt.
  290.  
  291. 2. Falls nicht: Funktion an 'nächsten' Handler weiterleiten.
  292.  
  293. Wer eine Mehrfachinstallation vornehmen möchte, sollte so vorgehen:
  294.  
  295. 1. Testen, ob `XHNewCookie()' zum Erfolg führt.
  296.  
  297. 2. Anderenfalls den Cookie `per Hand' versetzen.
  298.  
  299. ------------------------------------------------------------------------
  300. Opcode 10: LONG XHReadWrite (UWORD major, UWORD minor, UWORD rwflag,
  301.                              ULONG recno, UWORD count, void *buf);
  302.  
  303. Äquivalent zur BIOS-Funktion `Rwabs()' zum Lesen bzw. Schreiben 
  304. physikalischer Blocknummern.
  305.  
  306. rwflag:       Bits 0..2: wie in den AHDI-Release-Notes (3.00, 18. April
  307.               1990) beschrieben. Bit 3 (physikalischer Modus) wird
  308.               ignoriert. Alle weiteren Bits sind reserviert und auf Null zu
  309.               setzen.
  310. recno:        Sektornummer
  311. count:        Anzahl der Blöcke
  312. buf:          Zeiger auf Puffer.
  313.  
  314. -----------------------------------------------------------------------
  315. Opcode 11: LONG XHInqTarget2 (UWORD major, UWORD minor, ULONG *blocksize,
  316.                               ULONG *device_flags, char *product_name,
  317.                               UWORD stringlen);
  318.  
  319. - AB XHDI-Version 1.01 -
  320.  
  321. Liefert Informationen über das durch `major' und `minor' spezifizierte 
  322. Gerät (in `device_flags': ein Attributvektor, in `product_name': 
  323. optional die Produktbezeichnung des Geräts). Mit `XHReserve ()' 
  324. vorgenommene Reservierungen werden dabei berücksichtigt.
  325.  
  326. block_size:   Blockgrö₧e auf dem Gerät (für `XHReadWrite()' sehr wichtig).
  327.               Normalerweise 512.
  328.  
  329. device_flags: (Bit gesetzt -> Fähigkeit verfügbar):
  330.  
  331.       Bit 0:  Gerät kann gestoppt werden (XH_TARGET_STOPPABLE)
  332.       Bit 1:  Gerät hat wechselbare Medien (XH_TARGET_REMOVABLE)
  333.       Bit 2:  Auswurf des Geräts kann verriegelt werden
  334.               (XH_TARGET_LOCKABLE)
  335.       Bit 3:  Medium kann per Kommando ausgeworfen werden
  336.               (XH_TARGET_EJECTABLE)
  337.       Bit 29: Auswurf des Geräts ist vom Treiber blockiert worden 
  338.               (XH_TARGET_LOCKED, ab XHDI 1.25)
  339.       Bit 30: Gerät ist vom Treiber gestoppt worden (XH_TARGET_STOPPED, 
  340.               ab XHDI 1.25)
  341.       Bit 31: Geräte ist zur Zeit blockiert (XH_TARGET_RESERVED)
  342.  
  343.               Alle weiteren Bits sind reserviert und sollten vom Treiber
  344.               auf Null gesetzt werden.
  345.  
  346. product_name: Produktbezeichnung des Geräts (max. `stringlen' Zeichen inkl.
  347.               Leerzeichen). Falls die Information nicht verfügbar ist, wird
  348.               eine Zeichenkette der Länge Null zurückgeliefert.
  349.  
  350. stringlen:    Länge der für `product_name' übergebenen Zeichenkette.
  351.  
  352. Anmerkung: für `blocksize', `device_flags' und `product_name' dürfen 
  353. auch Nullzeiger übergeben werden. Produktbezeichnungen von IDE-Geräten 
  354. können bis zu 40 Zeichen lang sein.
  355.  
  356. -----------------------------------------------------------------------
  357. Opcode 12: LONG XHInqDev2 (UWORD bios_device, UWORD *major, UWORD *minor,
  358.                            ULONG *start_sector, BPB *bpb, ULONG *blocks,
  359.                            char *partid);
  360.  
  361. - AB XHDI-Version 1.10 -
  362.  
  363. Liefert Major Device Number, Minor Device Number, Startsektor, BPB (im 
  364. Gegensatz zu `Getbpb()' wird dadurch der Media-Change-Status des Geräts 
  365. NICHT zurückgesetzt), Länge und Partitionkennung (maximal drei Zeichen 
  366. zzgl. terminierender Null) eines BIOS-Geräts.
  367.  
  368. Anmerkung: es wird ein Zeiger auf eine vom Aufrufer bereitgestelle 
  369. BPB-Struktur übergeben, die vom XHDI-Treiber gefüllt wird.
  370.  
  371. Return-Wert: OK, EDRVNR (Gerät kann zur Zeit nicht angesprochen werden, 
  372. zum Beispiel Medium nicht eingelegt), EDRIVE (falsche Gerätenummer) oder 
  373. eine andere Fehlernummer. Bei EDRVNR darf man sich darauf verlassen, da₧ 
  374. `major' und `minor' korrekt zurückgeliefert werden.
  375.  
  376. Ein `start_sector' mit Wert $FFFFFFFF soll auf eine Partition hinweisen, 
  377. die zur Zeit vom Treiber nicht bedient wird (zum Beispiel, wenn ein 
  378. Wechselmedium mit 'zu wenig' Partitionen eingelegt ist).
  379.  
  380. Der zurückgelieferte BPB ist ungültig, wenn das Element `recsiz' Null ist.
  381.  
  382. Wenn die Partitionkennung nicht verfügbar ist (keine Atari-Partitionierung 
  383. oder überhaupt keine Partitionierung, beispielsweise bei normal 
  384. formatierten Disketten in SCSI-Diskettenlaufwerken), wird als 
  385. Partitionkennung eine leere Zeichenkette zurückgegeben.
  386.  
  387. Bei MSDOS-kompatibel partitionierten Medien wird ab XHDI-Version 1.20 die 
  388. ein Byte lange Partitionkennung wie folgt in `partid' abgelegt: partid[0] 
  389. = '\0' (Nullbyte), partid[1] = 'D' (für DOS), partid[2] = Kennung.
  390.  
  391. Hinweis: ein Dateisystem ist durch major- und minor-Gerätenummer sowie 
  392. Startsektor (mit der obigen Einschränkung) exakt spezifiziert. Über die 
  393. Art des Dateisystems (FAT oder etwas anderes) ist damit nichts ausgesagt!
  394.  
  395. Anmerkung: für `major', `minor', `start_sector', `bpb', `blocks' und 
  396. `partid' dürfen auch Nullzeiger übergeben werden.
  397.  
  398.  
  399. -----------------------------------------------------------------------
  400. Opcode 13: LONG XHDriverSpecial (ULONG key1, ULONG key2,
  401.                                  UWORD subopcode, void *data);
  402.  
  403. - OPTIONALE Funktion, darf also mit EINVFN beantwortet werden -
  404.  
  405. Dieser Opcode kann für treiberspezifische Erweiterungen benutzt werden. 
  406. Auf welche Art und Weise die Daten in `subopcode' und `data' interpretiert 
  407. werden, hängt ausschlie₧lich vom betroffenen Treiber ab. `key1' und `key2' 
  408. dienen zur Identifikation des anzusprechenden Treibers: `key1' sollte 
  409. dabei aus vier druckbaren ASCII-Zeichen bestehen, `key2' aus einem 
  410. möglichst willkürlich gewählten Long-Wert (etwa dem Datum der 
  411. Definition im BCD-Format).
  412.  
  413.  
  414. -----------------------------------------------------------------------
  415. Opcode 14: LONG XHGetCapacity (UWORD major, UWORD minor, ULONG *blocks,
  416.                                ULONG *blocksize);
  417.  
  418. - OPTIONALE Funktion, darf also mit EINVFN beantwortet werden -
  419.  
  420. Diese Funktion liefert in `blocks' die Anzahl der adressierbaren Sektoren 
  421. auf dem Medium und in `blocksize' ihre Grö₧e zurück (Vorsicht: je nach 
  422. verwendeter Hardware kann die Ausführung dieser Funktion mehrere Sekunden 
  423. dauern!).
  424.  
  425.  
  426. -----------------------------------------------------------------------
  427. Opcode 15: LONG XHMediumChanged (UWORD major, UWORD minor);
  428.  
  429. - OPTIONALE Funktion, darf also mit EINVFN beantwortet werden -
  430.  
  431. Informiert den Treiber darüber, da₧ das Medium in dem angegebenen Gerät 
  432. gewechselt worden ist. Der Treiber sollte daraufhin so vorgehen, als habe 
  433. das Gerät selbst einen Medienwechsel gemeldet. OK wird nur dann 
  434. zurückgeliefert, wenn die Information richtig verarbeitet wurde (also alle 
  435. logischen Laufwerke auf dem Gerät entweder deaktiviert sind oder benutzt 
  436. werden können).
  437.  
  438. -----------------------------------------------------------------------
  439. Opcode 16: LONG XHMiNTInfo (UWORD opcode, void *data);
  440.  
  441. - OPTIONALE Funktion, darf also mit EINVFN beantwortet werden -
  442.  
  443. Eine Funktion zum Setzen bzw. zur Abfrage MiNT-spezifischer Informationen.
  444.  
  445. Folgende Opcodes sind definiert (unbekannte Opcodes werden mit EINVFN 
  446. quittiert, OK wird genau dann zurückgeliefert, wenn die verlangte 
  447. Funktion korrekt ausgeführt werden konnte):
  448.  
  449. XH_MI_SETKERINFO (0) [struct kerinfo *data]
  450.  
  451. Übermittelt in `data' dem Treiber einen Zeiger auf die 
  452. MiNT-Kernel-Info-Struktur. Der Treiber kann diese benutzen, um 
  453. beispielsweise direkt Kernelfunktionen aufzurufen.
  454.  
  455. XH_MI_GETKERINFO (1) [struct kerinfo **data]
  456.  
  457. Erfragt beim Treiber die eventuell schon bekannte Adresse der 
  458. MiNT-Kernel-Info-Struktur. Der Zeiger auf die Struktur wird in die in 
  459. `data' angegebene Adresse geschrieben (wenn kein Treiber bekannt ist, wird 
  460. ein Nullzeiger zurückgeliefert).
  461.  
  462.  
  463. -----------------------------------------------------------------------
  464. Opcode 17: LONG XHDOSLimits (UWORD which, ULONG limit);
  465.  
  466. - OPTIONALE Funktion, darf also mit EINVFN beantwortet werden -
  467.  
  468. Diese Funktion erfragt beim Treiber die interne Limits des laufenden DOS 
  469. bzw. setzt sie. Sie kann zum Beispiel von einem FAT-Dateisystemtreiber 
  470. benutzt werden, um den Harddisk-Treiber mitzuteilen, da₧ sich einige 
  471. Limits geändert haben. `which' gibt an, welches Limit erfragt wird, 
  472. `limit' gibt den neuen Wert an (Null steht für: nicht ändern). Ergebnis 
  473. ist der bisherige Wert für das Limit.
  474.  
  475. Konstanten für `which':
  476.  
  477. XH_DL_SECSIZ (0): maximale Sektorgrö₧e auf BIOS-Ebene
  478. XH_DL_MINFAT (1): minimale Anzahl von FATs
  479. XH_DL_MAXFAT (2): maximale Anzahl von FATs
  480. XH_DL_MINSPC (3): Sektoren/Cluster minimal
  481. XH_DL_MAXSPC (4): Sektoren/Cluster maximal
  482. XH_DL_CLUSTS (5): maximale Clusterzahl
  483. XH_DL_MAXSEC (6): maximale Zahl von Sektoren
  484. XH_DL_DRIVES (7): maximale Zahl der vom DOS unterstützen BIOS-Laufwerke
  485.  
  486.  
  487. -----------------------------------------------------------------------
  488. Opcode 18: LONG XHLastAccess (UWORD major, UWORD minor, ULONG *ms);
  489.  
  490. - AB XHDI-Version 1.25 -
  491.  
  492. Liefert in `ms' zurück, wieviele Millisekunden seit dem letzten 
  493. erfolgreichen Lese- oder Schreibzugriff auf das Gerät vergangen sind.
  494.  
  495.  
  496. -----------------------------------------------------------------------
  497. Opcode 19: LONG XHReaccess (UWORD major, UWORD minor);
  498.  
  499. - AB XHDI-Version 1.25 -
  500.  
  501. Ein Aufruf dieser Funktion veranla₧t den Treiber, das angegebene Gerät auf 
  502. einen Mediachange zu überprüfen und gegebenenfalls die 
  503. Partitioninformationen entsprechend zu aktualisieren (wie 
  504. `XHMediumChanged()', nur da₧ der Treiber selbst das Gerät befragt, ob ein 
  505. Medienwechsel stattgefunden hat).
  506.  
  507.  
  508. ------------------------------------------------------------------------
  509.  
  510. Installation mehrerer Programme im XHDI-Cookie
  511. ----------------------------------------------
  512.  
  513. (1) Bei der Installation feststellen, ob der Cookie schon gesetzt ist.
  514.     Falls ja, müssen folgende zusätzliche Aufrufkonventionen
  515.     berücksichtigt werden:
  516.     
  517. (2) Bei `XHGetVersion()' zunächst durch den alten Vektor springen und dann
  518.     das Minimun der dort erhaltenen und der eigenen Versionsnummer
  519.     zurückliefern.
  520.     
  521. (3) Bei `XHDrvmap()' zunächst den alten Vektor durchspringen und
  522.     anschlie₧end die eigenen Drive-Bits hineinodern.
  523.     
  524. (4) Bei den anderen Funktionen: wenn es das eigene Gerät ist, normal
  525.     verfahren. Ansonsten: keinen Fehler melden, sondern durch den alten
  526.     Vektor springen.
  527.  
  528. -------------------------------------------------------------------------
  529.  
  530. Partitiontyp `RAW'
  531. ------------------
  532.  
  533. XHDI-1.10-kompatible Treiber müssen zusätzlich zu `GEM' und `BGM' den 
  534. dritten Partitiontyp `RAW' unterstützen. Für Partitionen dieses Typs 
  535. müssen folgende Eigenschaften unterstützt werden:
  536.  
  537. (1) Die Partitionlänge ist `beliebig' (im Rahmen der 32-Bit-Sektornummern).
  538.  
  539. (2) Die Partition ist als BIOS-Gerät ansprechbar; Getbpb() liefert einen
  540.     Nullzeiger (damit GEMDOS keinen Zugriff versucht, zusätzlich wird
  541.     auch der Media-Change-Status für das BIOS-Gerät zurückgesetzt). 
  542.  
  543. (3) Es kann per `Rwabs()' (nicht nur im physikalischen Modus) und
  544.     `XHReadWrite()' auf die Partition zugegriffen werden. Dabei wird
  545.     die physikalische Blockgrö₧e des Mediums benutzt (siehe
  546.     `XHInqTarget()').
  547.  
  548. (4) `XHInqDev2()' liefert im Gegensatz zu `XHInqDev()' auch die Länge und
  549.     den Typ der Partition zurück.
  550.  
  551. Diese Erweiterungen sollen die Programmierung zuverlässiger 
  552. Filesystemtreiber für MiNT (siehe zum Beispiel das Minix-FS) erleichtern.
  553.  
  554. -------------------------------------------------------------------------
  555.  
  556. Empfohlene Partitiontypen
  557. -------------------------
  558.  
  559. BGM     GEMDOS-Partition > 16 MB
  560. GEM     GEMDOS-Partition < 16 MB
  561. RAW     siehe oben
  562.  
  563. Folgende Typen können optional unterstützt (zum Beispiel anhand einer 
  564. konfigurierbaren Liste von Kennungen) werden.
  565.  
  566. MAC     Mac-HFS-Partition, sollte ggfs wie `RAW' behandelt werden
  567. MIX     Minix-Partition, sollte ggfs wie `RAW' behandelt werden
  568. QWA     QDOS-Partition, sollte ggfs wie `RAW' behandelt werden
  569. SWP     Swap-Partition, sollte ggfs wie `RAW' behandelt werden
  570. UNX     ASV (Atari Systen V R4), sollte ggfs wie `RAW' behandelt werden
  571.  
  572. -------------------------------------------------------------------------
  573.  
  574. Arbitration
  575. -----------
  576.  
  577. Für Gerätetreiber, die den SCSI-Bus arbitrierend betreiben wollen, mu₧ für 
  578. den Rechner eine eigene Gerätekennung vergeben werden. Diese sollte 
  579. natürlich einheitlich und nicht auf der Festplatte gespeichert sein. Atari 
  580. hat dafür Byte 16 im NVM des Atari TT und Falcon reserviert. Die 
  581. Bitbelegung ist:
  582.  
  583. Bit 0..2:   Gerätenummer
  584.    Bit 7:   Arbitration an (1) oder aus (0)
  585.  
  586. Die Abfrage der Gerätenummer könnte zum Beispiel wie folgt geschehen:
  587.  
  588. int
  589. arbitration_id (void)
  590. {
  591.     long ret = EINVFN;
  592.     unsigned char nvmdata = 0;
  593.     OSHEADER *Sys;
  594.     long oldstack = Super (0L);
  595.     Sys = *_sysbase;
  596.     Super ((void *)oldstack);
  597.  
  598.     host_id = -1;   /* no arbitration by default */
  599.  
  600.     if (Sys->os_version >= 0x300)
  601.         ret = NVMaccess (0, 16, (int) sizeof (nvmdata), &nvmdata);
  602.  
  603.     if (ret == E_OK && (nvmdata & 0x80))
  604.         host_id = nvmdata & 7;
  605.  
  606.     return host_id;
  607. }
  608.  
  609.